home *** CD-ROM | disk | FTP | other *** search
/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / pcp.idb / usr / share / catman / u_man / cat1 / pmgadgets.z.z / pmgadgets.z / pmgadgets
Text File  |  1997-04-03  |  33KB  |  595 lines
  1.  
  2.  
  3.  
  4. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ppppmmmmggggaaaaddddggggeeeettttssss - a miniature graphical performance metrics viewer
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ppppmmmmggggaaaaddddggggeeeettttssss [----CCCC] [----cccc _c_o_n_f_i_g] [----ddddeeeeffffaaaauuuullllttttffffoooonnnntttt _f_o_n_t] [----iiiinnnnffffooooffffoooonnnntttt _f_o_n_t] [----hhhh _h_o_s_t]
  13.      [----nnnn _n_a_m_e_s_p_a_c_e] [----tttt _u_p_d_a_t_e] [----zzzzoooooooommmm _f_a_c_t_o_r] [_s_t_a_n_d_a_r_d _X_1_1 _o_p_t_i_o_n_s]
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      ppppmmmmggggaaaaddddggggeeeettttssss creates a small window containing a collection of graphical
  17.      gadgets driven by performance metrics supplied by the Performance Co-
  18.      Pilot (PCP) framework.  Any numeric metric supported by PCP can be
  19.      displayed.  The layout of the gadgets and which performance metrics lie
  20.      behind them are specified in a configuration file.  The configuration
  21.      file syntax and gadgets are described in detail below.  Performance
  22.      metrics from several different hosts may be displayed simultaneously in
  23.      the same window.
  24.  
  25.      ppppmmmmggggaaaaddddggggeeeettttssss is typically run on an existing configuration file or in
  26.      conjunction with an application that automatically generates a
  27.      configuration file.  For example ppppmmmmggggiiiirrrriiiixxxx(1) generates a configuration
  28.      file for various IRIX performance metrics and feeds it to ppppmmmmggggaaaaddddggggeeeettttssss.
  29.  
  30.      The ----cccc option specifies the configuration file for ppppmmmmggggaaaaddddggggeeeettttssss to read.
  31.      Only one configuration file file should be specified.  If no
  32.      configuration file is specified, ppppmmmmggggaaaaddddggggeeeettttssss reads one from standard input.
  33.      If standard input is a terminal, a message warning the user what is
  34.      expected is printed.  The warning message may be suppressed by specifying
  35.      ---- as the configuration file.
  36.  
  37.      The ----CCCC option will parse the configuration file and exit before
  38.      displaying the ppppmmmmggggaaaaddddggggeeeettttssss window.  Any errors in the configuration file
  39.      are displayed.  This is useful for testing ppppmmmmggggaaaaddddggggeeeettttssss with different
  40.      configuration files for correctness.
  41.  
  42.      The ----ddddeeeeffffaaaauuuullllttttffffoooonnnntttt option overrides the default font used for label
  43.      gadgets.  Gadgets that do not explicitly specify a font in the
  44.      configuration file are drawn using the default font.  Unless this option
  45.      is used to override it, the default font used is 6x10.  The ----iiiinnnnffffooooffffoooonnnntttt
  46.      option may be used to override the font used in the information windows.
  47.      Unless this option is used to override it, the font used is 6x10.  _f_o_n_t
  48.      should be a valid X11 font specification.
  49.  
  50.      The ----hhhh option (or its synonym ----hhhhoooossssttttnnnnaaaammmmeeee) specifies the name of a default
  51.      host for ppppmmmmggggaaaaddddggggeeeettttssss to obtain performance metrics from.  Performance
  52.      metrics specified in the configuration file have an optional host name
  53.      part.  If the optional host name is not supplied, the default host will
  54.      be used.  If no ----hhhh option appears on the command line, localhost is used
  55.      as the default host.
  56.  
  57.      Normally ppppmmmmggggaaaaddddggggeeeettttssss operates on the default Performance Metrics Namespace
  58.      (PMNS), however if the ----nnnn option (or its synonym ----nnnnaaaammmmeeeessssppppaaaacccceeee) is specified
  59.      an alternative namespace is loaded from the file _n_a_m_e_s_p_a_c_e.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  71.  
  72.  
  73.  
  74.      An update interval for each gadget may be given explicitly in the
  75.      configuration file.  If it is not specified there, the default update
  76.      interval specified by the ----tttt (or its synonym ----ddddeeeellllttttaaaa) is used.  _u_p_d_a_t_e
  77.      should be a real or integral number of seconds.  If this option is not
  78.      specified, one second is used for the default update time.
  79.  
  80.      The ----zzzzoooooooommmm option may be used to specify an integral magnification factor.
  81.      Each gadget in the configuration file will have its size and position
  82.      multiplied by _f_a_c_t_o_r.  The zoom factor does not apply to text; the ----
  83.      ddddeeeeffffaaaauuuullllttttffffoooonnnntttt and ----iiiinnnnffffooooffffoooonnnntttt options must be used to change to font used to
  84.      draw text.
  85.  
  86.      ppppmmmmggggaaaaddddggggeeeettttssss also accepts many of the standard X Window System options (see
  87.      the options section of XXXX(1)).  Each of the command line options described
  88.      above may also be specified as an X11 resource.  The resource names are
  89.      the long form of the option name (e.g. delta for ----tttt).  The application
  90.      class name for ppppmmmmggggaaaaddddggggeeeettttssss is PmGadgets.
  91.  
  92.      ppppmmmmggggaaaaddddggggeeeettttssss reads its configuration file, contacts the Performance Metrics
  93.      Collector Daemon (PMCD) on each host mentioned in the configuration file
  94.      and validates that the performance metrics required are available.  If a
  95.      host or performance metric/instance is not available at start-up time,
  96.      ppppmmmmggggaaaaddddggggeeeettttssss will print an error message and exit.
  97.  
  98.      Once the configuration file has been processed ppppmmmmggggaaaaddddggggeeeettttssss creates a small
  99.      top-level window and displays a collection of small graphical gadgets
  100.      representing the performance metrics.  The gadgets are updated according
  101.      to the update intervals specified in the configuration file and the
  102.      command line.  If a gadget's metrics are unavailable, the gadget is
  103.      grayed out.
  104.  
  105.      Pressing the right mouse button inside the window brings up a popup menu
  106.      which allows one to terminate ppppmmmmggggaaaaddddggggeeeettttssss.  Pressing the escape key (Esc)
  107.      with the mouse pointer in the window will also terminate the application.
  108.      Pressing the middle mouse button over one of the gadgets in the window
  109.      will bring up a popup menu containing a list of actions for the gadget,
  110.      if appropriate.  Each gadget may have its own action list or share an
  111.      action list with other gadgets.  The action lists are defined in the
  112.      configuration file.  If there is a default action defined for a gadget,
  113.      double clicking on the gadget with the left mouse button invokes the
  114.      default action.
  115.  
  116.      Gadgets that display performance metrics' values will always have an Info
  117.      action, which will create a small window containing the names of the
  118.      metrics being displayed by the gadget along with their current values.
  119.      This can also be displayed by positioning the mouse pointer over the
  120.      gadget and pressing the space bar.  Note that each metric specification
  121.      contains the host name.  This can be used to determine which host is
  122.      being monitored if several ppppmmmmggggaaaaddddggggeeeettttssss windows are visible.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  137.  
  138.  
  139.  
  140.      ppppmmmmggggaaaaddddggggeeeettttssss is designed to take up a minimal amount of space on the screen.
  141.      For this reason, only the most rudimentary window frame is drawn around
  142.      it.  Text scaling is not supported by ppppmmmmggggaaaaddddggggeeeettttssss so the window may not be
  143.      resized while it is running.  The ----zzzzoooooooommmm option may be used to produce a
  144.      magnified view.
  145.  
  146. CCCCOOOONNNNFFFFIIIIGGGGUUUURRRRAAAATTTTIIIIOOOONNNN FFFFIIIILLLLEEEE SSSSYYYYNNNNTTTTAAAAXXXX
  147.      The configuration file consists of an optional header and a list of
  148.      clauses.  To make parsing easy, all reserved words begin with the
  149.      underscore character (____).  Comments begin with the #### character and finish
  150.      at the end of the same line.  Identifiers consist of an alphabetic
  151.      character followed by zero or more alphanumeric characters.  In the
  152.      descriptions below, brackets (e.g. [optional bit]) are used to indicate
  153.      optional parts of clauses.  Repetition is indicated with ellipses (...).
  154.      Lexical elements in bold should appear verbatim (e.g.  [[[[ means use a
  155.      literal bracket rather than indicating an optional component of a
  156.      clause).  Strings should be delimited by double quotes (e.g.  """"xxxxccccoooonnnnffffiiiirrrrmmmm
  157.      ----tttt ''''nnnnooootttt iiiimmmmpppplllleeeemmmmeeeennnntttteeeedddd''''"""").  For convenience, the double quotes may be
  158.      omitted if the string is a valid identifier.
  159.  
  160.      The optional header must be the first line in the configuration file that
  161.      isn't a comment or blank line.  It consists of ppppmmmmggggaaaaddddggggeeeettttssss 1111
  162.  
  163.      Action lists are used to build popup menus for gadgets.
  164.  
  165.      ____aaaaccccttttiiiioooonnnnssss _n_a_m_e (((( _a_c_t_i_o_n ...))))
  166.  
  167.      Creates an action list called _n_a_m_e.  Each _a_c_t_i_o_n should be of the form:
  168.  
  169.      _a_c_t_i_o_n__n_a_m_e _a_c_t_i_o_n__s_t_r_i_n_g [____ddddeeeeffffaaaauuuulllltttt]
  170.  
  171.      _a_c_t_i_o_n__n_a_m_e specifies a name for the action.  This name will be used in
  172.      the menu that is created for the action list.  _a_c_t_i_o_n__s_t_r_i_n_g specifies a
  173.      shell command to be executed when the action is selected from the menu.
  174.      _a_c_t_i_o_n__n_a_m_e and _a_c_t_i_o_n__s_t_r_i_n_g should both be strings.  If ____ddddeeeeffffaaaauuuulllltttt is
  175.      present, it signifies the default action for the action list.  There may
  176.      be only one default action in an action list.
  177.  
  178.      Color lists are used to conveniently name a group of colors.  This allows
  179.      similar gadgets to share a group of colors.
  180.  
  181.      ____ccccoooolllloooorrrrlllliiiisssstttt _n_a_m_e (((( _c_o_l_o_r__n_a_m_e ... ))))
  182.  
  183.      Creates a list of colors called _n_a_m_e, which must be a valid identifier.
  184.      Each _c_o_l_o_r__n_a_m_e should be a valid X11 colour specification.  If the
  185.      specification is not a valid identifier, it should be enclosed in double
  186.      quotes (e.g. """"rrrrggggbbbb::::ffffffffffffffff////0000////0000"""").  For those that speak English rather than
  187.      American, ____ccccoooolllloooouuuurrrrlllliiiisssstttt is accepted as an alternative spelling of
  188.      ____ccccoooolllloooorrrrlllliiiisssstttt....
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  203.  
  204.  
  205.  
  206.      Legends are used to associate colors with numeric thresholds.  Legends
  207.      are used to color-code numeric performance metric values.
  208.  
  209.      ____lllleeeeggggeeeennnndddd _n_a_m_e (((( _t_h_r_e_s_h_o_l_d ... ))))
  210.  
  211.      Creates a legend called _n_a_m_e, which must be a valid identifier.  Each
  212.      _t_h_r_e_s_h_o_l_d should be of the form
  213.  
  214.      _n_u_m_b_e_r _c_o_l_o_r__n_a_m_e
  215.  
  216.      or
  217.  
  218.      ____ddddeeeeffffaaaauuuulllltttt _c_o_l_o_r__n_a_m_e
  219.  
  220.      _n_u_m_b_e_r may be either a floating point or integral value.  When a
  221.      performance metric's value is to be represented as a color using a
  222.      legend, the color corresponding to the greatest _n_u_m_b_e_r in the legend less
  223.      than or equal to the metric's value is used.  If the metric's value is
  224.      less than the smallest threshold, the ____ddddeeeeffffaaaauuuulllltttt color is used.
  225.  
  226.      The position and size of a gadget is given using a _g_e_o_m_e_t_r_y__s_p_e_c, which
  227.      must be of the following form:
  228.  
  229.      _x__p_o_s _y__p_o_s _w_i_d_t_h _h_e_i_g_h_t
  230.  
  231.      _x__p_o_s and _y__p_o_s are integers that specify the position of the top left
  232.      corner of the gadget, relative to the top left corner of the window.  X
  233.      values increase from left to right and Y values increase from top to
  234.      bottom.  _w_i_d_t_h and _h_e_i_g_h_t should be positive integers.  All units are in
  235.      pixels.
  236.  
  237.      ppppmmmmggggaaaaddddggggeeeettttssss adds a margin to the bottom and right edges of its window.  The
  238.      margin at the right edge is the same as the X position of the leftmost
  239.      gadget in the configuration file.  Similarly, the bottom margin is the Y
  240.      position of the gadget with the minimum Y position.
  241.  
  242.      The line gadget is just a horizontal or vertical line, with no underlying
  243.      performance metrics:
  244.  
  245.      ____lllliiiinnnneeee _g_e_o_m_e_t_r_y__s_p_e_c [_a_c_t_i_o_n_s]
  246.  
  247.      The _g_e_o_m_e_t_r_y__s_p_e_c is the bounding box of the line, which will be filled.
  248.      E.g. to create a horizontal line 2 pixels high and 8 pixels wide at (5,
  249.      5) one would use a _g_e_o_m_e_t_r_y__s_p_e_c of 5 5 8 2.  To create a vertical line
  250.      of the same thickness and length starting at the same point, the
  251.      _g_e_o_m_e_t_r_y__s_p_e_c would be 5 5 2 8.  _a_c_t_i_o_n_s is optional and should be of the
  252.      form:
  253.  
  254.      ____aaaaccccttttiiiioooonnnnssss _n_a_m_e
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  269.  
  270.  
  271.  
  272.      where _n_a_m_e specifies the name of a previously defined action list.  If
  273.      present, the action list defines the contents of the popup menu under
  274.      mouse button two.
  275.  
  276.      A label gadget specifies a piece of text.  Only a single line of text may
  277.      be displayed by a label gadget.  A label specification should be of the
  278.      form:
  279.  
  280.      ____llllaaaabbbbeeeellll _x__p_o_s _y__p_o_s _t_e_x_t [_f_o_n_t__s_p_e_c] [_a_c_t_i_o_n_s]
  281.  
  282.      _x__p_o_s and _y__p_o_s specify the baseline origin of the label, not the top
  283.      left corner.  _t_e_x_t is the label text; normally _t_e_x_t would be enclosed in
  284.      double quotes, however these may be omitted if _t_e_x_t is a valid
  285.      identifier.  _f_o_n_t__s_p_e_c is a valid X Window System font name.  If the font
  286.      name is not a valid identifier it should be enclosed in double quotes.
  287.      Refer to the XXXX(1) manual page for details of font naming.  If the
  288.      _f_o_n_t__s_p_e_c is omitted, the default font specified on the command line is
  289.      used.  If no default font was specified, the font 6x10 is used.  _a_c_t_i_o_n_s
  290.      is optional and should specify the name of a previously defined action
  291.      list.
  292.  
  293.      Performance metrics specifications usually appear in configuration files.
  294.      A _m_e_t_r_i_c__s_p_e_c has the form:
  295.  
  296.      [_h_o_s_t:]metric[[[[[_i_n_s_t_a_n_c_e]]]]]
  297.  
  298.      Where _h_o_s_t (and its accompanying colon) are optional and specify the host
  299.      from which the metric will be fetched.  If no host is specified in the
  300.      configuration file, the default host is used.  If no default host was
  301.      specified on the command line, the default host is localhost.  _m_e_t_r_i_c
  302.      specifies a PCP performance metric name.  _i_n_s_t_a_n_c_e must be enclosed in
  303.      brackets if it is present.  It specifies which instance of the
  304.      performance metric is required.  The instance must be specified in double
  305.      quotes if it is not a valid identifier.  If _m_e_t_r_i_c has instances (is not
  306.      a single-valued metric), an instance must be specified.  There is no
  307.      instance wildcarding.
  308.  
  309.      The bar gadget displays a single performance metric value.  It is a
  310.      rectangle that is filled from left to right or bottom to top in
  311.      proportion to the ratio of the metric's value to some maximum.  The
  312.      maximum may be either a fixed number specified in the configuration file,
  313.      or the highest value of the metric seen so far.  A bar gadget
  314.      specification has the form:
  315.  
  316.      ____bbbbaaaarrrr _g_e_o_m_e_t_r_y__s_p_e_c [_u_p_d_a_t_e] ____mmmmeeeettttrrrriiiicccc _m_e_t_r_i_c__s_p_e_c [_b_a_r__d_e_t_a_i_l ...]
  317.      [_b_a_r__c_o_l_o_r] [_a_c_t_i_o_n_s]
  318.  
  319.      _u_p_d_a_t_e specifies an optional update interval for the gadget.  It should
  320.      have the form
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  335.  
  336.  
  337.  
  338.      ____uuuuppppddddaaaatttteeee _d_e_l_t_a
  339.  
  340.      A new value of the underlying performance metric is fetched every _d_e_l_t_a
  341.      seconds and the gadget is redrawn in accord.  _b_a_r__d_e_t_a_i_l specifies either
  342.      an orientation (____hhhhoooorrrriiiizzzzoooonnnnttttaaaallll or vvvveeeerrrrttttiiiiccccaaaallll) or a bound.  A bound consists of
  343.      ____mmmmiiiinnnniiiimmmmuuuummmm, ____mmmmiiiinnnn, ____mmmmaaaaxxxxiiiimmmmuuuummmm or ____mmmmaaaaxxxx followed by a numeric value.
  344.      Contradictory _b_a_r__d_e_t_a_i_ls are not permitted.
  345.  
  346.      If no bounds are specified, the gadget dynamically adjusts its maximum to
  347.      the greatest value of the metric that has been fetched.  The default
  348.      minimum is zero.  If a maximum is specified, it is used as an initial
  349.      maximum value, but if a greater value for the metric is fetched, the
  350.      bar's maximum will be increased accordingly.  The same is true for the
  351.      bar's minimum.  For example if no minimum is specified and the value of
  352.      the metric fetched is -10, the bar's minimum is adjusted from 0 (the
  353.      default) to -10.  The proportion of the bar that is filled is the ratio
  354.      of two differences: the metric's current value minus the minimum and the
  355.      maximum minus the minimum.
  356.  
  357.      If the word ____ffffiiiixxxxeeeedddd appears before ____mmmmaaaaxxxxiiiimmmmuuuummmm the maximum and minimum will
  358.      not be adjusted in this way.  If the metric's value exceeds the fixed
  359.      maximum, a contrasting arrowhead is drawn in the completely filled bar.
  360.      If the metric's value falls below the fixed minimum a contrasting
  361.      arrowhead is drawn in the unfilled bar.  It is not possible to have a
  362.      fixed maximum and a floating minimum or vice versa.
  363.  
  364.      _b_a_r__c_o_l_o_r is optional and should have the form
  365.  
  366.      ____ccccoooolllloooouuuurrrr _c_o_l_o_r__n_a_m_e
  367.  
  368.      Where _c_o_l_o_r__n_a_m_e is a valid X11 colour specification.  If the
  369.      specification is not a valid identifier, it should be enclosed in double
  370.      quotes (e.g. """"rrrrggggbbbb::::ffffffffffffffff////0000////0000"""").  For those that speak English rather than
  371.      American, ____ccccoooolllloooouuuurrrr is accepted as an alternative spelling of ____ccccoooolllloooorrrr....
  372.      _a_c_t_i_o_n_s is optional and should specify the name of a previously defined
  373.      action list.
  374.  
  375.      If no value is available for the bar gadget's performance metric, the
  376.      gadget is grayed out.
  377.  
  378.      The multibar gadget is similar to the bar gadget, but displays several
  379.      performance metrics at the same time.  Each is allocated a color and the
  380.      gadget's rectangle is filled with an amount of each colour proportional
  381.      to the ratio of the corresponding performance metric's contribution to a
  382.      maximum value.  The maximum may be a fixed value, the sum of the current
  383.      values of the gadget's metrics (utilization) or the greatest sum of the
  384.      gadget's metrics seen so far.  A multibar gadget specification has the
  385.      form:
  386.  
  387.      ____mmmmuuuullllttttiiiibbbbaaaarrrr _g_e_o_m_e_t_r_y__s_p_e_c [_u_p_d_a_t_e] _m_e_t_r_i_c_s__l_i_s_t [_s_c_a_l_i_n_g] ____ccccoooolllloooorrrrlllliiiisssstttt _c_o_l_o_r_s
  388.      [_a_c_t_i_o_n_s]
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  401.  
  402.  
  403.  
  404.      _u_p_d_a_t_e specifies an optional update interval for the gadget as described
  405.      above.  _m_e_t_r_i_c_s__l_i_s_t should have the form
  406.  
  407.      ____mmmmeeeettttrrrriiiiccccssss (((( _m_e_t_r_i_c__s_p_e_c ... ))))
  408.  
  409.      If no _s_c_a_l_i_n_g is specified, the multibar gadget plots each metric's
  410.      contribution to the greatest sum of metric values seen so far.  The
  411.      maximum is initially set to a small positive value (0.000001).  If a
  412.      _s_c_a_l_i_n_g of the form
  413.  
  414.      [____ffffiiiixxxxeeeedddd] ____mmmmaaaaxxxxiiiimmmmuuuummmm _n_u_m_b_e_r
  415.  
  416.      is specified, different semantics are used.  If ____ffffiiiixxxxeeeedddd appears, the fixed
  417.      maximum specified by _n_u_m_b_e_r is used.  If the sum of the metrics exceeds
  418.      the maximum, the gadget is drawn stippled with the quantity of each
  419.      colour in proportion to the contribution of the corresponding metric to
  420.      the sum of the metrics values.  If the sum is less than the maximum, the
  421.      gadget will be drawn normally.  If ____ffffiiiixxxxeeeedddd is omitted and a non-zero
  422.      maximum is specified, it specifies an initial maximum sum, but this
  423.      maximum will be adjusted if a higher sum is observed.  If ____ffffiiiixxxxeeeedddd is
  424.      omitted and a maximum of zero is specified, the maximum will be set to
  425.      the sum of the metrics' current values every time the metrics are
  426.      fetched.  This shows each metric's contribution as a fraction of the
  427.      current sum of all of the metrics' values.  If the sum of the metrics in
  428.      such a multibar is zero, the multibar is grayed out.  _c_o_l_o_r_s should
  429.      specify the name of a previously defined color list.  Metrics in the
  430.      metrics list are paired with the corresponding entry in the color list.
  431.      The two lists should be the same length.  The information window for a
  432.      multibar gadget contains the metric names and the corresponding colors.
  433.      _a_c_t_i_o_n_s is optional and should specify the name of a previously defined
  434.      action list.
  435.  
  436.      The bargraph gadget displays a simple xxxxllllooooaaaadddd(1) style strip chart of a
  437.      performance metric's values over time.  A bargraph gadget specification
  438.      should have the form:
  439.  
  440.      ____bbbbaaaarrrrggggrrrraaaapppphhhh _g_e_o_m_e_t_r_y__s_p_e_c [_u_p_d_a_t_e] ____mmmmeeeettttrrrriiiicccc _m_e_t_r_i_c__s_p_e_c [_s_c_a_l_i_n_g ... ]
  441.      [_a_c_t_i_o_n_s]
  442.  
  443.      A history of _w_i_d_t_h - 1 values of the the performance metric's values are
  444.      displayed on the bargraph (_w_i_d_t_h is taken from the _g_e_o_m_e_t_r_y__s_p_e_c).  The
  445.      oldest value appears at the left and new values are added to the right,
  446.      pushing older values to the left.  _u_p_d_a_t_e specifies an optional update
  447.      interval for the gadget as described above.  _s_c_a_l_i_n_g should be either
  448.      ____mmmmaaaaxxxxiiiimmmmuuuummmm or ____mmmmiiiinnnniiiimmmmuuuummmm followed by a number to specify an initial upper
  449.      and/or lower bound for the bargraph.  The minimum and maximum are
  450.      dynamically adjusted to the most extreme values of the underlying
  451.      performance metric seen so far.  A maximum or minimum that has scrolled
  452.      off the left edge of the bargraph will continue to exert its effect.  By
  453.      default, the minimum bound is zero.  Normally the height of the bar drawn
  454.      at a point is proportional to the ratio of difference between the
  455.      metric's value there and its lowest historical value to the greatest
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  467.  
  468.  
  469.  
  470.      metric range seen so far.  The metric range is the difference between the
  471.      historical maximum and minimum.  If no value was available for the
  472.      underlying metric a stippled, gray bar, the full height of the bargraph
  473.      is drawn.
  474.  
  475.      If the word ____ffffiiiixxxxeeeedddd appears before ____mmmmaaaaxxxxiiiimmmmuuuummmm the maximum and minimum will
  476.      not be adjusted in this way.  If the metric's value exceeds the fixed
  477.      maximum, a contrasting coloured segment is drawn at the top of a
  478.      completely filled bar.  If the metric's value falls below the fixed
  479.      minimum a contrasting segment is drawn where the bottom of the bar would
  480.      normally appear.  It is not possible to have a fixed maximum and a
  481.      floating minimum or vice versa.
  482.  
  483.      _a_c_t_i_o_n_s is optional and should specify the name of a previously defined
  484.      action list.
  485.  
  486.      The LED gadget is a threshold-based representation of a performance
  487.      metric.  As the metric exceeds some numeric threshold a different colour
  488.      is drawn.  A LED gadget specification has the form:
  489.  
  490.      ____lllleeeedddd _g_e_o_m_e_t_r_y__s_p_e_c [_u_p_d_a_t_e] ____mmmmeeeettttrrrriiiicccc _m_e_t_r_i_c__s_p_e_c ____lllleeeeggggeeeennnndddd _n_a_m_e [_a_c_t_i_o_n_s]
  491.  
  492.      _u_p_d_a_t_e specifies an optional update interval for the gadget as described
  493.      above.  _n_a_m_e should specify a previously defined legend.  _a_c_t_i_o_n_s is
  494.      optional and should specify the name of a previously defined action list.
  495.  
  496. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  497.      Running ppppmmmmggggiiiirrrriiiixxxx(1) with the ----ccccoooonnnnffffiiiigggg flag causes it to print its
  498.      configuration file to standard output rather than feeding it to
  499.      ppppmmmmggggaaaaddddggggeeeettttssss.
  500.  
  501. FFFFIIIILLLLEEEESSSS
  502.      ////vvvvaaaarrrr////ppppccccpppp////ppppmmmmnnnnssss////*         default PMNS specification files
  503.      ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////aaaapppppppp----ddddeeeeffffaaaauuuullllttttssss////PPPPmmmmGGGGaaaaddddggggeeeettttssss
  504.                              X11 application default resources
  505.      ////vvvvaaaarrrr////ppppccccpppp////lllliiiibbbb////ppppmmmmggggaaaaddddggggeeeettttssss----aaaarrrrggggssss
  506.                              Shell procedures that assist in the creation of
  507.                              front-end scripts for pmgadgets.
  508.  
  509. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  510.      ppppmmmmggggiiiirrrriiiixxxx(1), ppppmmmmiiiinnnnffffoooo(1), ppppmmmmccccdddd(1), XXXX(1).
  511.  
  512. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  513.      Various errors will be generated in response to invalid configuration
  514.      files.  Unavailable hosts, metrics or instances may also produce error
  515.      messages.
  516.  
  517. EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT
  518.      Front-end tools using /_v_a_r/_p_c_p/_l_i_b/_p_m_g_a_d_g_e_t_s-_a_r_g_s are will report error
  519.      messages and warings using xxxxccccoooonnnnffffiiiirrrrmmmm(1) if $$$$DDDDIIIISSSSPPPPLLLLAAAAYYYY is set, otherwise
  520.      diagnostic output is written to standard error.  If the $$$$PPPPCCCCPPPP____UUUUSSSSEEEE____SSSSTTTTDDDDEEEERRRRRRRR
  521.      environment variable is set, diagnostic messages are forced to standard
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))                                                      PPPPMMMMGGGGAAAADDDDGGGGEEEETTTTSSSS((((1111))))
  533.  
  534.  
  535.  
  536.      error.
  537.  
  538. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  539.      If any of the performance metrics in the configuration file are not
  540.      available, ppppmmmmggggaaaaddddggggeeeettttssss will not start.
  541.  
  542.      There are hard-wired limitations on the number of hosts, metrics and
  543.      instances specified in the configuration file. There can only be at most
  544.      1111000022224444 hosts, 222255556666 metrics and 4444000099996666 instances.  Multiple occurences of the
  545.      same instances (e.g. irix.disk.dev.total["dks0d1"]) also get counted in
  546.      this number.  If any of the limits is exceeded, the program will halt
  547.      with the appropriate error message.
  548.  
  549.      There is currently no way to pass the ----hhhh option through to programs
  550.      specified in an action list.  Programs that generate configuration files
  551.      automatically must explicitly generate actions that pertain to a remote
  552.      host.  For example ppppmmmmggggiiiirrrriiiixxxx(1) uses its ----hhhh option to generate actions that
  553.      refer to the remote host.
  554.  
  555.      If the time required to fetch performance metrics exceeds the update
  556.      interval for the metrics, ppppmmmmggggaaaaddddggggeeeettttssss may not have time to (re)draw the
  557.      gadgets before the next fetch begins.  In pathological cases there may
  558.      not even be time to process user input.
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.                                                                         PPPPaaaaggggeeee 9999
  592.  
  593.  
  594.  
  595.